---
sidebar_label: Metadata format
sidebar_position: 6
description: Metadata formats
keywords:
  - hasura
  - format
  - Metadata
toc_max_heading_level: 6
---

# Metadata Format Reference

## Introduction

With Metadata config `v3`, the Metadata that is exported from the server by the CLI is a directory of multiple files and
directories as per the example below:

```text
📂 metadata
├─ 📂 databases
│  ├─ 📄 databases.yaml
│  └─ 📂 default
│     ├─ 📂 tables
│     │  ├─ 📄 public_author.yaml
│     │  ├─ 📄 public_article.yaml
│     │  └─ 📄 tables.yaml
│     └─ 📂 functions
│        ├─ 📄 public_search_author.yaml
│        └─ 📄 functions.yaml
├─ 📄 actions.graphql
├─ 📄 actions.yaml
├─ 📄 allow_list.yaml
├─ 📄 api_limits.yaml
├─ 📄 cron_triggers.yaml
├─ 📄 graphql_schema_introspection.yaml
├─ 📄 inherited_roles.yaml
├─ 📄 network.yaml
├─ 📄 metrics_config.yaml
├─ 📄 opentelemetry.yaml
├─ 📄 query_collections.yaml
├─ 📄 remote_schemas.yaml
├─ 📄 rest_endpoints.yaml
└─ 📄 version.yaml
```

Internally in Hasura Server, Metadata is maintained as a JSON blob in the `hdb_metadata` table of the Metadata database.

:::info note

For `config v2`, see
[Metadata format reference (config v2)](/migrations-metadata-seeds/legacy-configs/config-v2/reference/metadata-format.mdx).

:::

## Metadata directory format

The following files will be generated in the `metadata/` directory of your project:

:::info Note

The output of the [export_metadata](/api-reference/metadata-api/manage-metadata.mdx#metadata-export-metadata) Metadata
API is a JSON version of the Metadata files.

:::

### databases

```text
📂 databases
├─ 📄 databases.yaml
└─ 📂 default
  ├─ 📂 tables
  │  ├─ 📄 public_author.yaml
  │  ├─ 📄 public_article.yaml
  │  └─ 📄 tables.yaml
  └─ 📂 functions
     ├─ 📄 public_search_author.yaml
     └─ 📄 functions.yaml
```

#### databases.yaml

```yaml
- name: default
  kind: postgres
  configuration:
    connection_info:
      use_prepared_statements: false
      database_url:
        from_env: PG_DATABASE_URL
      isolation_level: read-committed
  tables: '!include default/tables/tables.yaml'
```

:::info Note

`database_url` can be set as a string literal by omitting the `from_env` property.

:::

#### [database-name]

Directory with Metadata related to a database.

```text
📂 default
├─ 📂 tables
│  ├─ 📄 public_author.yaml
│  ├─ 📄 public_article.yaml
│  └─ 📄 tables.yaml
└─ 📂 functions
   ├─ 📄 public_search_author.yaml
   └─ 📄 functions.yaml
```

##### tables

Directory with Metadata related to a database's tables and views.

```text
📂 tables
├─ 📄 public_author.yaml
├─ 📄 public_article.yaml
└─ 📄 tables.yaml
```

###### tables.yaml

The `tables.yaml` file contains a list of all further database table `yaml` files which need to be included in the
metadata.

**Example**: A `tables.yaml` file which specifies further `author` and `article` table files

```yaml
- '!include public_author.yaml'
- '!include public_article.yaml'
```

###### [table-name].yaml

The specific files for each database table contain all the Metadata information regarding each database table.

These files can contain information relating to the table for:

- Relationships including object and array relationships
- Remote relationships including those to Remote Schemas and remote databases
- Operation permissions per role
- Event Triggers
- Computed fields
- Whether the table is an enum table
- GraphQL field customization

**Example**: A `public_author.yaml` table Metadata file specifying some of the above.

```yaml
table:
  name: author
  schema: public
array_relationships:
  - name: articles
    using:
      foreign_key_constraint_on:
        column: author_id
        table:
          name: article
          schema: public
insert_permissions:
  - role: user
    permission:
      check:
        id:
          _eq: X-Hasura-User-Id
      set:
        id: x-hasura-user-id
      columns:
        - name
select_permissions:
  - role: user
    permission:
      columns:
        - id
        - name
      filter:
        id:
          _eq: X-Hasura-User-Id
      allow_aggregations: true
      query_root_fields:
        - select
        - select_by_pk
      subscription_root_fields:
        - select
        - select_by_pk
delete_permissions:
  - role: user
    permission:
      backend_only: true
      filter: {}
event_triggers:
  - name: author_created
    definition:
      enable_manual: false
      insert:
        columns: '*'
    retry_conf:
      interval_sec: 10
      num_retries: 0
      timeout_sec: 60
    webhook: http://httpbin.org/post
```

##### functions

Directory with Metadata related to a database's functions tracked to be exposed as top-level GraphQL fields.

```text
📂 functions
├─ 📄 public_search_author.yaml
└─ 📄 functions.yaml
```

###### functions.yaml

The `functions.yaml` file contains a list of all further database function `yaml` files which need to be included in the
Metadata to be exposed as top-level GraphQL fields.

**Example**: A `functions.yaml` file which specifies further `search_author` function file

```yaml
- '!include public_search_author.yaml'
```

###### [function-name].yaml

The specific files for each database function contain all the Metadata information regarding exposing the database
function as a top-level GraphQL field.

**Example**: A `public_search_author.yaml` function Metadata file

```yaml
function:
  name: search_author
  schema: public
permissions:
  - role: user
```

### actions.graphql

The `actions.graphql` file contains all the GraphQL [Actions](/actions/overview.mdx) and their
[custom type](/actions/types.mdx) definitions.

**Example**: A query action called `greet` and two custom types called `SampleInput` and `SampleOutput`

```graphql
type Query {
  greet(arg1: SampleInput!): SampleOutput
}
input SampleInput {
  username: String!
}
type SampleOutput {
  greetings: String!
}
```

### actions.yaml

The `actions.yaml` file contains Metadata related to [actions](/actions/overview.mdx).

**Example**: An action called `greet` with the `handler` set to `<base_url>/greet` and two custom types called
`SampleInput` and `SampleOutput`

```yaml
actions:
  - name: greet
    definition:
      kind: ''
      handler: <base_url>/greet
      forward_client_headers: true
      headers:
        - value: application/json
          name: Content-Type
custom_types:
  enums: []
  input_objects:
    - name: SampleInput
  objects:
    - name: SampleOutput
  scalars: []
```

**Example**: Same example as above but with the base URL of the `handler` passed as an environment variable

```yaml
actions:
  - name: greet
    definition:
      kind: ''
      handler: '{{ACTION_BASE_URL}}/greet'
      forward_client_headers: true
      headers:
        - value: application/json
          name: Content-Type
custom_types:
  enums: []
  input_objects:
    - name: SampleInput
  objects:
    - name: SampleOutput
  scalars: []
```

### allow_list.yaml

The `allow_list.yaml` file contains the Metadata related to the [allow list](/security/allow-list.mdx).

**Example**: A query collection called `allowed-queries` set as the allow-list

```yaml
- collection: allowed-queries
```

### api_limits.yaml

For Hasura Cloud and Hasura Enterprise the `api_limits.yaml` file contains the Metadata related to
[api limits](/security/api-limits.mdx).

**Example**: An api limit setting with global limits and a specific limit for a `customer` role

```yaml
depth_limit:
  global: 10
  per_role:
    customer: 5
disabled: false
node_limit:
  global: 10
  per_role:
    customer: 5
rate_limit:
  global:
    max_reqs_per_min: 100
    unique_params: null
  per_role:
    customer:
      max_reqs_per_min: 60
      unique_params: null
time_limit:
  global: 10
  per_role:
    customer: 5
```

### cron_triggers.yaml

The `cron_triggers.yaml` file contains Metadata related to [cron triggers](/scheduled-triggers/create-cron-trigger.mdx).
The `webhook` can be an HTTP endpoint or an environment variable containing the HTTP endpoint.

**Example**: A cron trigger called `test-trigger`

```yaml
- name: test-trigger
webhook: <webhook-url>
schedule: 0 12 * * 1-5
include_in_metadata: true
payload: {}
retry_conf:
  num_retries: 1
  timeout_seconds: 60
  tolerance_seconds: 21600
  retry_interval_seconds: 10
```

:::info Note

The Metadata about a cron trigger will not be stored if `Include this trigger in Hasura Metadata` is disabled in the
advanced option of `events` on the Console or `include_in_metadata` is passed as `false` via the API.

:::

### graphql_schema_introspection.yaml

For Hasura Cloud and Hasura Enterprise the `graphql_schema_introspection.yaml` file enables disabling of GraphQL
introspection for specified roles.

**Example**: Disabling introspection for roles `customer` and `user`

```yaml
disabled_for_roles:
  - customer
  - user
```

### inherited_roles.yaml

The `inherited_roles.yaml` file contains Metadata related to [inherited roles](/auth/authorization/inherited-roles.mdx).

**Example**: An inherited role of `manager` which inherits from `user` and `customer`

```yaml
- role_name: manager
  role_set:
    - user
    - customer
```

### network.yaml

The `network.yaml` file contains Metadata related to [network options](/api-reference/metadata-api/network.mdx).

**Example**: A TLS Allowlist to represent a set of services that are permitted to use self-signed certificates

```yaml
tls_allowlist:
  - host: graphql.hasura.io
    permissions:
      - self-signed
    suffix: core.graphql
```

### metrics_config.yaml

The `metrics_config.yaml` file contains Metadata related to configuratbility of which GraphQL-related entities are
observable via metrics for debugging and analytics. All values are boolean. More information can be found
[here](/api-reference/metadata-api/observability.mdx#logs-and-metrics-configuration).

**Example**: Enabling metrics for query-variable analysis, and disabling metrics for the resposne body

```yaml
analyze_query_variables: true
analyze_response_body: false
```

### opentelemetry.yaml

The `opentelemetry.yaml` file contains Metadata related to configuring your OpenTelemetry receiver. More information can
be found [here](/observability/opentelemetry/index.mdx).

An example `opentelemetry.yaml` takes this shape:

```yaml
status: enabled
data_types:
  - traces
exporter_otlp:
  headers:
    - name: x-test-header
      value: testing
    - name: x-header-from-env
      value_from_env: TEST_ENV_VAR
  resource_attributes:
    - name: stage
      value: production
    - name: region
      value: us-east
  otlp_traces_endpoint: http://host.docker.internal:4318/v1/traces
  protocol: http/protobuf
batch_span_processor:
  max_export_batch_size: 512
```

### query_collections.yaml

The `query_collections.yaml` file contains Metadata information about
[query collections](/api-reference/metadata-api/query-collections.mdx).

**Example**: A query collection called `sample-collection` which contains two queries `test` and `test2`

```yaml
- name: sample-collection
  definition:
    queries:
      - name: test
        query: |-
          query test {
            books {
              id
              author_id
              title
            }
          }
      - name: test2
        query: |-
          query test2 {
              authors{
                  id
                  author_name
              }
          }
```

### remote_schemas.yaml

The `remote_schemas.yaml` file contains the Metadata related to [Remote Schemas](/remote-schemas/overview.mdx).

**Example**: A Remote Schema called `my-remote-schema` with the URL `<remote-schema-url>`

```yaml
- name: my-remote-schema
  definition:
    url: <remote-schema-url>
    timeout_seconds: 40
```

**Example**: A Remote Schema called `my-remote-schema` with the URL passed as environment variable

```yaml
- name: my-remote-schema
  definition:
    url_from_env: REMOTE_SCHEMA
    timeout_seconds: 40
```

### rest_endpoints.yaml

The `rest_endpoints.yaml` file contains the Metadata related to [REST endpoints](/api-reference/restified.mdx).

**Example**: An example of a defined restified endpoint which gets an author based on their `id`

```yaml
- comment: Get an author based on their id
  definition:
    query:
      collection_name: allowed-queries
      query_name: Author by Id
  methods:
    - GET
  name: Author by Id
  url: author/:id
```

### version.yaml

The `version.yaml` file contains the Metadata format version.

```yaml
version: 3
```
